ATSUGetGlyphBounds

OSStatus ATSUGetGlyphBounds (
                     ATSUTextLayout iTextLayout,
                     ATSUTextMeasurement iTextBasePointX,
                     ATSUTextMeasurement iTextBasePointY,
                     UniCharArrayOffset iBoundsCharStart,
                     UniCharCount iBoundsCharLength,
                     UInt16 iTypeOfBounds,
                     ItemCount iMaxNumberOfBounds,
                     ATSTrapezoid oGlyphBounds[],
                     ItemCount *oActualNumberOfBounds);

iTextLayout

A reference of type ATSUTextLayout. Pass a reference to an initialized text layout object. You cannot pass NULL for this parameter.

iTextBasePointX

A value of type ATSUTextMeasurement. Pass the x-coordinate of the origin of the line (in the current graphics port) whose typographic glyph bounds you want to calculate. Pass 0 if you just want the dimensions of the bounds with respect to one another, not their actual onscreen position. Pass the constant kATSUUseGrafPortPenLoc, described in Current Pen Location Constant, if you want the dimensions of the bounds relative to the current pen location in the current graphics port.

iTextBasePointY

A value of type ATSUTextMeasurement. Pass the y-coordinate of the origin of the line (in the current graphics port) whose typographic glyph bounds you want to calculate. Pass 0 if you just want the dimensions of the bounds with respect to one another, not their actual onscreen position. Pass the constant kATSUUseGrafPortPenLoc, described in Current Pen Location Constant, if you want the dimensions of the bounds relative to the current pen location in the current graphics port.

iBoundsCharStart

A value of type UniCharArrayOffset. Pass the edge offset corresponding to the beginning of the range of text whose typographic glyph bounds you want to calculate. To indicate the beginning of the text buffer, pass the constant kATSUFromTextBeginning, described in Text Offset Constant. To indicate the entire text buffer, pass kATSUFromTextBeginning in this parameter and the constant kATSUToTextEnd in the iBoundsCharLength parameter. If the offset is outside the text buffer, ATSUGetGlyphBounds returns the result code kATSUInvalidTextRangeErr.

iBoundsCharLength

A value of type UniCharCount. Pass the length of the range of text whose onscreen typographic glyph bounds you want to obtain. To indicate the end of the text buffer, pass the constant kATSUToTextEnd, described in Text Length Constant. To indicate the entire text buffer, pass kATSUToTextEnd in this parameter and the constant kATSUFromTextBeginning in the iBoundsCharStart parameter. If the range of text is outside the text buffer, ATSUGetGlyphBounds returns the result code kATSUInvalidTextRangeErr.

iTypeOfBounds

The type of origin used in calculating the dimensions of the typographic bounds. See Glyph Bound Constants for a description of possible values.

iMaxNumberOfBounds

The maximum number of enclosing trapezoids you want passed back. Typically, this is equivalent to the number of bounds in the oGlyphBounds array. To determine this value, see the discussion below.

oGlyphBounds

An array of structures of type ATSTrapezoid. Before calling ATSUGetGlyphBounds, pass a pointer to memory that you have allocated for this array. If you are uncertain of how much memory to allocate, see the discussion below. On return, the array contains the enclosing trapezoid(s) representing the typographic bounds of a range of text. If the specified range of text encloses directional boundaries, ATSUGetGlyphBounds will pass back multiple trapezoids defining these regions. In ATSUI 1.1, the maximum number of enclosing trapezoids that can be returned in 31; in ATSUI 1.2, the maximum number is 127. You cannot pass NULL for this parameter.

oActualNumberOfBounds

A pointer to a count. On return, the actual number of enclosing trapezoids bounding the specified character(s). This may be greater than the value passed in the iMaxNumberOfBounds parameter. You cannot pass NULL for this parameter.

function result

A result code. See Result Codes.

DISCUSSION

The ATSUGetGlyphBounds function returns the rotated final typographic bounds in multiple trapezoids, if needed, taking into account line rotation, flushness, and justification. It passes back the enclosing trapezoid(s) that represent the typographic glyph bounds of a range of text.

To obtain the typographic bounding rectangle around a line of text prior to line layout, call the function ATSUMeasureText. To calculate the standard bounding rectangle around a final laid-out line, call the function ATSUMeasureTextImage.

Before calculating the typographic glyph bounds of a range of text, ATSUGetGlyphBounds examines the text layout object to make sure that the style runs cover the entire range of text. If there are gaps between style runs, ATSUGetGlyphBounds assigns the characters in the gap to the style run following the gap. If there is no style run at the beginning of the range of text, ATSUGetGlyphBounds assigns these characters to the first style run it can find. If there no style run at the end of the range of text, ATSUGetGlyphBounds assigns the remaining characters to the last style run it can find.

The coordinates of each trapezoid are offset by the amount specified in the iTextBasePointX and iTextBasePointY parameters. If you want to draw the typographic bounds on the screen, pass the position of the origin of the line in the current graphics port in these parameters. This enables ATSUGetGlyphBounds to match the trapezoids to their onscreen image.

The height of the trapezoid(s) is determined by the line ascent and descent attribute values you previously set for the line. If you have not set these values for the line, ATSUGetGlyphBounds will use the values set for the text layout object containing the line. If neither have been set, ATSUGetGlyphBounds will use the natural line ascent and descent calculated for the line. The width of the trapezoid(s) is determined using the caret origin, glyph origin in device space, or glyph origin in fractional absolute positions, depending upon the value you pass in the iTypeOfBounds parameter.

You should call ATSUGetGlyphBounds to do your own text highlighting, using the fractional origin (instead of the device origin) for the width of the highlight.

VERSION NOTES

Available beginning with ATSUI 1.1.